Endpoint Common Features

Some aspects of the Keyfactor APIClosed An API is a set of functions to allow creation of applications. Keyfactor offers the Keyfactor API, which allows third-party software to integrate with the advanced certificate enrollment and management features of Keyfactor Command. request and response formats are consistent across all endpoints. This includes a small set of HTTP headers, HTTP statuses returned by the server for successful requests, and various error conditions. Common request headers are given in Table 145: Common Request Headers, common response headers (for successful requests and certain unsuccessful requests) are given in Table 146: Common Response Headers, and HTTP statuses are given in Table 147: HTTP Statuses.

By default, all Keyfactor API methods start with a base path, which corresponds to an application under IIS; this path is configurable at install time. The default base path is KeyfactorApi. The API component name and method name then comprise the parts of the URL, each separated by a forward slash. For example, /KeyfactorApi/Certificates/Import would be the URL format for the Import method of the Certificates component.

Table 145: Common Request Headers

Header Name

Header Value

Description

Content-Type

application/json

OR

application/xml

POST methods use application/json. When application/xml is needed, it is specifically indicated on the endpoint page.

Accept

application/json; charset=utf-8

Most methods returning complex values will use this content type.

Authorization

Basic <base-64 DOMAIN\user:pass>

OR

Bearer <OAuth 2.0 token>

For more information about authenticating to the Keyfactor API, see Authenticating to the Keyfactor API.

Host

<Keyfactor Command server hostname>

Address of Keyfactor Command server. Automatically generated in most clients.

Content-Length

Request length in bytes

Optional, but automatically generated by most clients.

X-Keyfactor-Requested-With

XMLHttpRequest

This is mandatory to send in a request to the Keyfactor API on POSTs, PUTs, and DELETEs, and the value is case sensitive. This is for security.

X-Keyfactor-API-Version 1 or 2 Desired version of the endpoint. If not provided, this defaults to version 1.

Table 146: Common Response Headers

Header Name

Header Value

Description

api-supported-versions 1.0, 2 The supported endpoint versions for the Keyfactor API.

Cache-Control

no-cache

API requests are generally not cacheable. Note that this is not respected by all client systems.

Content-Length

<varies>

Length of the HTTP response.

Content-Type

application/json

Most calls return application/json, but occasionally text/plain or text/xml.

Date

<varies>

Timestamp of the HTTP response.

Expires

-1

Usually ignored.

Pragma

no-cache

API requests are generally not cacheable. Note that this is not respected by all client systems.

Server

<varies>

Software version reported by IIS platform hosting Keyfactor Command.

Strict-Transport-Security max-age=31536000; includeSubDomains When Keyfactor Command is configured with HTTP Strict Transport Security (HSTS) as per Keyfactor recommended configuration (see Configure the Keyfactor Command Server to Require SSL).

X-AspNet-Version

<varies>

Version of ASP.NET supporting Keyfactor Command installation.

X-Keyfactor-Correlation-Id <varies> GUID indicating the correlation ID of the request. This is used to help identify log messages that originate from the request.
X-Keyfactor-Product-Version <varies> Keyfactor Command platform version.

X-Powered-By

ASP.NET

Header added by underlying ASP.NET implementation.

X-Total-Count

<varies>

Total number of elements returned.

Table 147: HTTP Statuses

Number/Name

Description

200 OK

Request successful; results in response body

204 No Content

Request successful; no content in response body

400 Bad Request

Malformed or invalid data; additional information may be available in the response body and/or Keyfactor Command server logs

401 Unauthorized

Invalid credentials (user unauthenticated)

403 Forbidden

Can often indicate that the credentials map to a user without permissions for this action in Keyfactor Command (user unauthorized)

404 Page not Found

Invalid request path

500 Internal Server Error

Keyfactor Command encountered an unexpected error attempting to handle the request. See response body and Keyfactor Command server logs for details.

502 Bad Gateway

Keyfactor Command attempted to contact a CA or other upstream server to process the request, but was unable to. See Keyfactor Command server logs for details.